home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / IC++ 1.0b2 / IC APIs / ICAPI.h next >
Text File  |  1995-06-27  |  12KB  |  257 lines
  1. /*
  2.     IMPORTANT NOTES ABOUT THE C CONVERSION
  3.     --------------------------------------
  4.     
  5.     o Pascal "var" parameters are converted from "var x : y" to "y *x".  This
  6.       means that when you see the parameter "y *x" you should be aware that
  7.             you *cannot pass in nil*.  In future this restriction may be eased,
  8.             especially for the attr parameter to ICGetPref.  Parameters where nil
  9.             is legal are declared using the explicit pointer type, ie "yPtr x".
  10.  
  11.     o Strings are *Pascal* strings.  This means that they must be word aligned.
  12.         MPW and Think C do this automatically.  The last time I check, Metrowerks
  13.         C does not.  If it still doesn't, then IMHO it's a bug in their compiler
  14.         and you should report it to them.
  15.  
  16.     o The canonical Internet Config interface is defined in Pascal.  These
  17.         headers have not been thoroughly tested.  If there is a conflict between
  18.         these headers and the Pascal interfaces, the Pascal should take precedence.
  19. */
  20.  
  21. /* ///////////////////////////////////////////////////////////////////////////////// */
  22.  
  23. #ifndef __ICAPI__
  24. #define __ICAPI__
  25.  
  26. #ifndef __TYPES__
  27. #include <Types.h>
  28. #endif
  29.  
  30. #ifndef __FILES__
  31. #include <Files.h>
  32. #endif
  33.  
  34. #ifndef __ICTYPES__
  35. #include "ICTypes.h"
  36. #endif
  37.  
  38. #ifndef __ICKEYS__
  39. #include "ICKeys.h"
  40. #endif
  41.  
  42. /* ///////////////////////////////////////////////////////////////////////////////// */
  43.  
  44. #ifdef __cplusplus
  45. extern "C" {
  46. #endif
  47.  
  48.     pascal ICError ICStart(ICInstance *inst, OSType creator);
  49.     /* call at application initialisation */
  50.  
  51.     pascal ICError ICStop(ICInstance inst);
  52.     /* call at application termination */
  53.  
  54.     pascal ICError ICFindConfigFile(ICInstance inst, short count, ICDirSpecArrayPtr folders);
  55.     /* count is the number of ICDirSpecs that are valid in folders */
  56.     /* searches the specified folders first, then backs out to preferences folder */
  57.     /* don't you worry about how it finds the file (; */
  58.     /* you can pass nil to folders if count is 0 */
  59.  
  60.     pascal ICError ICFindUserConfigFile(ICInstance inst, ICDirSpec *where);
  61.     /* requires IC 1.1 */
  62.     /* similar to ICFindConfigFile except */
  63.     /* For use with double clickable preference files, this searches only the where directory */
  64.  
  65.     pascal ICError ICSpecifyConfigFile(ICInstance inst, FSSpec *config);
  66.     /* for use *only* by Internet Configuration application */
  67.  
  68.     pascal ICError ICGetSeed(ICInstance inst, long *seed);
  69.     /* returns current seed for prefs file */
  70.     /* this seed changes every time a preference is modified */
  71.     /* poll this to detect preference changes by other applications */
  72.  
  73.     pascal ICError ICGetPerm(ICInstance inst, ICPerm *perm);
  74.     /* returns the permissions currently associated with this file */
  75.     /* mainly used by overriding components, applications normally */
  76.     /* know what permissions they have */
  77.  
  78.     pascal ICError ICBegin(ICInstance inst, ICPerm perm);
  79.     /* start reading/writing the preferences */
  80.     /* must be balanaced by a ICEnd */
  81.     /* do not call WaitNextEvent between this pair */
  82.     /* specify either icReadOnlyPerm or icReadWritePerm */
  83.     /* note that this may open resource files and leave them open until ICEnd */
  84.  
  85.     pascal ICError ICGetPref(ICInstance inst, ConstStr255Param key, ICAttr *attr, Ptr buf, long *size);
  86.     /* this routine may be called without a ICBegin/ICEnd pair, in which case */
  87.     /* it implicitly calls ICBegin(inst, icReadOnlyPerm */
  88.     /* given a key string, returns the attributes and the (optionally) the data for a preference */
  89.     /* key must not be the empty string */
  90.     /* if buf is nil then no data fetched and incoming size is ignored*/
  91.     /* size must be non-negative, is size of allocated space for data at buf */
  92.     /* attr and size and always set on return */
  93.     /* size is actual size of data (if key present); */
  94.     /* attr is pref attributes */
  95.      /* if icTruncatedErr then everything is valid, except you lost some data, size is size of real data*/
  96.     /* on other errors, attr is ICattr_no_change and size is 0 */
  97.  
  98.     pascal ICError ICSetPref(ICInstance inst, ConstStr255Param key, ICAttr attr, Ptr buf, long size);
  99.     /* this routine may be called without a ICBegin/ICEnd pair, in which case */
  100.     /* it implicitly calls ICBegin(inst, icReadWritePerm */
  101.     /* given a key string, sets the attributes and the data for a preference (either is optional); */
  102.     /* key must not be the empty string */
  103.     /* if buf is nil then no data stored and size is ignored, used for setting attr */
  104.     /* size must be non-negative, is size of the data at buf to store */
  105.     /* icPermErr if ICBegin was given icReadOnlyPerm */
  106.     /* icPermErr if current attr is locked, new attr is locked and buf <> nil */
  107.  
  108.     pascal ICError ICGetPrefHandle(ICInstance inst, ConstStr255Param key, ICAttr *attr, Handle *prefh);
  109.     /* same as ICGetPref except that it returns the result in a newly created handle */
  110.     /* attr must not be nil */
  111.     /* prefh is set to a newly created handle */
  112.  
  113.     pascal ICError ICSetPrefHandle(ICInstance inst, ConstStr255Param key, ICAttr attr, Handle prefh);
  114.     /* same as ICSetPref except that it sets the preference based on a handle */
  115.     /* prefh must not be nil */
  116.  
  117.     pascal ICError ICCountPref(ICInstance inst, long *count);
  118.     /* count total number of preferences */
  119.     /* if error then count is 0 */
  120.  
  121.     pascal ICError ICGetIndPref(ICInstance inst, long n, Str255 key);
  122.     /* return the key of the Nth preference */
  123.     /* n must be positive */
  124.     /* icPrefNotFoundErr if n is beyond the last preference */
  125.  
  126.     pascal ICError ICDeletePref(ICInstance inst, ConstStr255Param key);
  127.     /* delete the preference specified by key */
  128.     /* key must not be the empty string */
  129.     /* preference specified by key must be present */
  130.     /* icPrefNotFoundErr if it isn't */
  131.  
  132.     pascal ICError ICEnd(ICInstance inst);
  133.     /* stop reading/writing the preferences */
  134.  
  135.     pascal ICError ICDefaultFileName(ICInstance inst, Str63 name);
  136.     /* return the default file name */
  137.     /* the component calls this routine to set up the default internet configuration file name*/
  138.     /* this allows this operation to be intercepted by a component that has captured us */
  139.     /* it currently gets it from the component resource file */
  140.     /* the glue version is hardwired */
  141.  
  142.     pascal ICError ICGetComponentInstance(ICInstance inst, Ptr *component_inst);
  143.     /* returns noErr and the component instance that we're talking to, if we're using the component */
  144.     /* returns an error and nil if we're doing it with glue */
  145.  
  146.     pascal ICError ICEditPreferences(ICInstance inst, ConstStr255Param key);
  147.     /* requires IC 1.1 */
  148.     /* this routine may be called without a ICBegin/ICEnd pair */
  149.     /* open the IC application and edits the preference */
  150.     /* you must have found a config file before calling this */
  151.     /* if key is empty then it just opens the application with the found config file */
  152.     /* otherwise it displays the preference with the specified key */
  153.     /* may have an implementation that is radically different in the future */
  154.  
  155.     pascal ICError ICParseURL(ICInstance inst, ConstStr255Param hint, Ptr data, long len, long *selStart, long *selEnd, Handle url);
  156.     /* requires IC 1.1 */
  157.     /* this routine may be called without a ICBegin/ICEnd pair */
  158.     /* parses a URL out of a chunk of text and returns it in a canonical form */
  159.     /* hint is an indication of how you want slack URLs to be parsed */
  160.     /* data points to the beginning of the text */
  161.     /* len is the length of the text */
  162.     /* selStart is the start of the current selection */
  163.     /* selEnd is the end of the current selection */
  164.     /* both of these are interpreted as per TextEdit */
  165.     /* both of these are adjusted to indicate the bounds of the text that was interpreted as a URL */
  166.     /* the URL is copied into the url handle, which is resized to accomodate the URL */
  167.  
  168.     pascal ICError ICLaunchURL(ICInstance inst, ConstStr255Param hint, Ptr data, long len, long *selStart, long *selEnd);
  169.     /* requires IC 1.1 */
  170.     /* this routine may be called without a ICBegin/ICEnd pair */
  171.     /* identical to ParseURL but it launches the appropriate application (as specified in the 'Helper•' preference */
  172.     /* and sends it a GURL AppleEvent */
  173.     /* your code must be running in the context of a high level event aware application for this to work */
  174.  
  175.     /* ----- Mappings Routines ----- */
  176.  
  177.     /* Routines for interrogating mappings database */
  178.     /* All of these routines require IC 1.1 */
  179.  
  180.     /* High Level Routines */
  181.  
  182.     /* you do not need to call begin/end around any of these high level routines */
  183.     /* but if you're going to call them repeatedly, it will help */
  184.  
  185.     pascal ICError ICMapFilename(ICInstance inst, ConstStr255Param filename, ICMapEntry *entry);
  186.     /* high level interface to the mappings database */
  187.     /* takes a filename and returns the incoming entry associated with that file's extension */
  188.     /* or errors with icPrefNotFoundErr */
  189.  
  190.     pascal ICError ICMapTypeCreator(ICInstance inst, OSType fType, OSType fCreator, ConstStr255Param filename, ICMapEntry *entry);
  191.     /* high level interface to the mappings database */
  192.     /* takes a filename and returns the outgoing entry associated with that type, creator and filename */
  193.     /* or errors with icPrefNotFoundErr */
  194.  
  195.     /* Mid Level Routines */
  196.  
  197.     /* you do not need to call begin/end around any of these mid level routines */
  198.  
  199.     pascal ICError ICMapEntriesFilename(ICInstance inst, Handle entries, ConstStr255Param filename, ICMapEntry *entry);
  200.     /* mid level interface to the mappings database */
  201.     /* entries must be a valid IC mappings database handle */
  202.     /* takes a filename and returns the incoming entry associated with that file's extension */
  203.     /* or errors with icPrefNotFoundErr */
  204.  
  205.     pascal ICError ICMapEntriesTypeCreator(ICInstance inst, Handle entries, OSType fType, OSType fCreator, ConstStr255Param filename, ICMapEntry *entry);
  206.     /* mid level interface to the mappings database */
  207.     /* entries must be a valid IC mappings database handle */
  208.     /* takes a filename and returns the outgoing entry associated with that type, creator and filename */
  209.     /* or errors with icPrefNotFoundErr */
  210.  
  211.     /* Low Level Routines */
  212.  
  213.     /* you do not need to call begin/end around any of these low level routines */
  214.  
  215.     pascal ICError ICCountMapEntries(ICInstance inst, Handle entries, long *count);
  216.     /* entries must be a valid IC mappings database handle */
  217.     /* count the number of entries in the Mappings database */
  218.  
  219.     pascal ICError ICGetIndMapEntry(ICInstance inst, Handle entries, long ndx, long *pos, ICMapEntry *entry);
  220.     /* entries must be a valid IC mappings database handle */
  221.     /* return the ndx'th entry in the mappings database */
  222.     /* ndx must be from 1 to CountMapEntries */
  223.     /* pos is ignored on input and comes back as the position of the entry in the database */
  224.     /* entry is ignored on input and comes back as the database entry at the ndx position */
  225.  
  226.     pascal ICError ICGetMapEntry(ICInstance inst, Handle entries, long pos, ICMapEntry *entry);
  227.     /* entries must be a valid IC mappings database handle */
  228.     /* return the entry at position pos */
  229.     /* pos should be a valid entry start position */
  230.     /* set pos to 0 for the first entry */
  231.     /* set pos to pos + entry.total_size for subsequent entries */
  232.     /* entry is ignored on input and comes back as the database entry at position pos */
  233.  
  234.     pascal ICError ICSetMapEntry(ICInstance inst, Handle entries, long pos, ICMapEntry *entry);
  235.     /* entries must be a valid IC mappings database handle */
  236.     /* set the entry at position pos */
  237.     /* pos should be a valid entry start position */
  238.     /* any user data at the end of the entry is preserved */
  239.     /* entry is not modified, it's a var parameter simply to preserve stack space */
  240.  
  241.     pascal ICError ICDeleteMapEntry(ICInstance inst, Handle entries, long pos);
  242.     /* entries must be a valid IC mappings database handle */
  243.     /* delete the entry at position pos */
  244.     /* pos should be a valid entry start position */
  245.     /* also deletes the user data associated with the entry */
  246.  
  247.     pascal ICError ICAddMapEntry(ICInstance inst, Handle entries, ICMapEntry *entry);
  248.     /* entries must be a valid IC mappings database handle */
  249.     /* add entry to the mappings database */
  250.     /* entry is not modified, it's a var parameter simply to preserve stack space */
  251.  
  252. #ifdef __cplusplus
  253. }
  254. #endif // __cplusplus
  255.  
  256. #endif
  257.